.\" $FreeBSD$
.Dd Aug 19, 2011
.Dt porttree 1
.Os FreeBSD 8.2
.Sh NAME
.Nm porttree
.Nd Show dependences of a FreeBSD port as a pseudo graphical tree
.Sh SYNOPSIS
.Nm
.Op Fl f | -fetch-depends
.Op Fl e | -extract-depends
.Op Fl p | -patch-depends
.Op Fl b | -build-depends
.Op Fl l | -lib-depends
.Op Fl r | -run-depends
.Op Fl n | -number-all
.Op Fl s Ar st | Fl -style Ar st
.Op Fl A | -all-ports
.Op Fl R | -reverse
.Op Fl O | -others
.Op Fl S Ar filename | Fl -save Ar filename
.Op Fl U Ar filename | Fl -use-saved Ar filename
.Op Ar category/portname...
.Sh DESCRIPTION
The
.Nm
utility is a tool for visualizing dependences of a port and ports dependent on
the given ports if used with 
.Fl A Fl R .
Without any options, all kinds of dependences will be tracked and shown,
same as if all of them are given.
This will show, e.g. ports needed to patch a port, which is necessary to fetch 
the given port.
Only given types of dependences will be used if any of them are present 
in the command line.
.Pp
Use style 0 on a terminal without pseudo graphic chars (e.g. ISO-8859-15),
or switch the encoding of the terminal to utf-8, cp855, or similar. 
E.g.
.Xr gnome-terminal 1
allows to choose the encoding.
.Sh OPTIONS
The options are as follows:
.Bl -tag -width F1
.It Fl f | Fl -fetch-depends
Show ports necessary to fetch the target port.
.It Fl e | Fl -extract-depends
Show ports necessary to extract the target port.
.It Fl p | Fl -patch-depends
Show ports necessary to patch the target port.
.It Fl b | Fl -build-depends
Show ports necessary to build the target port.
.It Fl l | Fl -lib-depends
Show ports installing libraries necessary for the target port.
.It Fl r | Fl -run-depends
Show ports necessary to run the target port.
.It Fl n | Fl -number-all
Number all lines of the output,
even the lines with reference to previously shown ports.
By default, this lines are not numbered,
thus the biggest line number indicates the total number of dependences.
.It Fl s Ar st | Fl -style Ar st
Use pseudo graphic chars style 
.Ar st .
Few styles are defined at the moment:
.Bl -tag -width F1
.It Ar -1
- (default) check for availability of Alternative Character Set (ACS) in
termcap/terminfo capabilities of the terminal where the program is running and
use it or fall back to the ASCII-only mode. This part was written with help
from Oliver Fromme.
.It Ar 0
- use usual chars only (like
.Sq | ,
.Sq ` ,
and
.Sq + ) .
.It Ar 1
- single line pseudo graphics. For a previously shown port name,
add after the name an arrow with the line number where it was shown.
Also, a branching to nowhere symbol is added before the port name,
if it has further dependences.
.It Ar 2
- same as 1, but use double line pseudo graphics.
.It Ar 3
- same as 1, but no indication of branching for previously shown ports.
.It Ar 4
- same as 3, but use double line pseudo graphics.
.It Ar 5
- unconditionally use ACS pseudo graphics of xterm/vt100 terminal.
.El
.It Fl A | Fl -all-ports
Traverse whole ports tree, then show dependences of the given ports.
.It Fl R | Fl -reverse
Show also reversed dependences, i.e. show ports depending on the given one.
.It Fl O | Fl -others
After the dependences of the given ports are shown,
show also the not previously shown ports with their dependences.
Together with
.Fl A ,
this can be used to show all ports.
.It Fl P Ar dir | Fl -save Ar dir
Use the given directory to find the ports instead of the default
.It /usr/ports .
.It Fl S Ar filename | Fl -save Ar filename
Save the interdependences data to the file
.Ar filename .
.It Fl U | Fl -unsave
Read the interdependences data from the file
.Ar filename .
.El
.Pp
Try the current directory if no portname is given.
Portnames are to be given either as full pathnames or as
.Ar category/port
within the portsdir.
In the results, the portsdir is removed from the beginning of the pathnames.
.Sh EXAMPLES
The following are examples of typical usage of the
.Nm
command:
.Pp
All dependences and dependents of gcc44, and save the data in the file
.Ar cache
for future use:
.Dl "porttree -A -R -S cache lang/gcc44"
Same used on a console with default screenmap:
.Dl "porttree -s 1 -AR -S cache lang/gcc44 | iconv -f utf-8 -t cp437"
Using previously saved in the file 
.Ar cache
data for python32:
.Dl "porttree -U cache -R /usr/ports/lang/python32"
./" .Nm
./" port:
./" .Dl "porttree ports-mgmt/porttree"
./" produces for port installed without GENDIST option the following.
./" .Bf -literal
./" 0 +ports-mgmt/porttree
./" 1 \`+math/py-networkx
./" 2  \`+lang/python27
./" .Ef
.Sh AUTHORS
The program and this manual page were written by
.An Vladimir Chukharev.
.Sh BUGS
Styles 3 and 4 use arrow chars which could not be converted by
.Xr iconv 1
to console charsets (e.g. cp437).
.Pp
Practically no check is done for usefulness of used option combinations.
E.g.
.Fl A
is silently ignored with
.Fl U Ar filename .
On the other hand,
.Fl S Ar filename
overwrites a good saved file with nearly empty one if 
.Fl A
is not given with it.
.Sh "SEE ALSO"
.Xr iconv 1 , Xr ports 7
